A multi-tasking computerised index to magazines and manuals
Magazine databases are Copyright © Beebug Limited 1991
Manual databases are Copyright © Acorn & Beebug Limited 1991
Program is Copyright © Lee Calcraft & Beebug Limited 1991
All rights reserved
No part of this product may be reproduced in whole or part by any means without written permission of the publisher. Unauthorised hiring, renting, loaning, public performance or broadcasting of this product or its constituent parts is prohibited.
While every care is taken, the publisher cannot be held responsible for any errors in this product, or for the loss of any data or consequential effects from the use of this package.
| FIRST EDITION | 1990 |
| REPRINTED | 1990 |
| SECOND EDITION | 1991 |
| HTML EDITION | 2000 |
| Published by | Beebug Limited |
| 117 Hatfield Road, St. Albans, Herts, AL1 4JS, England. | |
| Tel: 0727 40303 Fax: 0727 860263 |
ArcScan is supplied with data files for RISC User and BEEBUG magazines, and for the indexes of major Archimedes manuals published by Acorn, including the following:
User Guide (Arthur/Basic)
Programmer's Reference Manual (Arthur)
User Guide (RISC OS)
Basic Guide (RISC OS)
RISC OS User Guide
Programmer's Reference Manual (RISC OS)
ANSI C Manual (Acorn)
Fortran 77 Manual (Acorn)
Note that the RISC OS User Guide has the same pagination as the A3000 User Guide.
ArcScan Library discs containing data covering the contents of other magazines such as Acorn User and Micro User are available separately.
| ArcScan itself | |
| !System resources | |
| and | !ReadMe |
Before running ArcScan, please run the !ReadMe application by double-clicking on its icon in the directory viewer. This application will tell you about recent updates to ArcScan, or additions to the databases supplied with this package.
ArcScan itself is run in the usual way from the Desktop. Insert the disc into your drive, and click on the drive icon on the icon bar. Then simply double-click on the ArcScan icon in the directory viewer.
This will cause the ArcScan icon to be installed on the icon bar. Clicking on this will open ArcScan's main window - the control panel. A second window, used for displaying search results and other information will be opened when a search is made, or when a new database is selected.
RISC User
RISC OS 3 Manuals
If no database is currently loaded, you should click on one of these icons to load the data you require before making a search.
It is an easy matter to alter the way in which the manuals are selected, or to remove particular manual indexes where such information is of no use to the user. Moreover ArcScan's handling of individual databases has been made user-customisable via a special file (called !Custom), making it easy to include databases for other magazines or for completely different kinds of material. The only real limitation is that there is a maximum of eight databases in any incarnation of ArcScan, and that the line length used in each record must be no greater than 40 characters.
If you wish to rearrange files in the two Manuals directories, you may do so freely - without the need to alter the !Custom file. For example, to remove a particular manual, just delete its file from the directory. For details of more extensive customisation, see Customisation.
Almost instantaneously any finds will be displayed in the Finds window. You can scroll through these using the Select button on the Scroll up and down icons (Adjust reverses the direction of scroll), or by dragging the scroll bar slider to the required position. Alternatively, if you click the mouse either above or below the scroll bar slider, this will have a Page up or Page down effect.
The control panel provides two writable icons for entering search strings. The Up and Down arrow keys can be used to take you between these, while Return will take you from the first to the second, or if you are on the second, will initiate a search. If you are using a single search string, there is a small shortcut which you may find useful. If you hold down the Shift key while pressing Return when the caret is in the upper writable icon, your search will commence immediately; and afterwards the caret will remain in the upper icon ready for any editing which may be required.
| OR | |
| AND | |
| and | NOT |
If OR is selected (the default), then ArcScan will find all records which contain either the first or the second string. If AND is selected, then only those records containing both the first and the second string will be displayed, while if NOT is selected, only those records which contain the first string but not the second will be found.
For example, if your two strings are Utility and Disc, and you use AND logic, you will only be shown entries where both words occur somewhere in the record (though the two words do not need to be adjacent to one another, or in any particular order). If on the other hand you select OR logic, all entries containing either Utility or Disc will be displayed.
The logical NOT option may occasionally be useful. For example you might wish to search for all references to Pipedream which are not News items. A search for:
Pipedream
NOT
News
will do the trick.
Note that in order to search for strings containing the asterisk or hash characters themselves ("*" or "#"), use "/*" or "/#". Thus:
/*FX
will find all references to *FX. To enter a slash character for its own sake use // (though there is no real need for this since the slash character as entered with // is treated exactly like a single space).
In the RISC User database it is possible to search for certain types of item. News, Hints, Reviews, Disc-only items, and Visuals always have a title which commences with a unique keyword followed by a colon. Thus if you search for:
News:
you will find all news items. Similarly,
Review:
will find all reviews, while:
Disc:
will find all items which appear only on the magazine disc.
To search for a particular item within such a grouping, use AND logic with your chosen keyword. For example, to find all reviews of wordprocessors, use:
Review:
AND
Wordproc*
or for reviews of all painting packages, use:
Review:
AND
Paint*
With a little thought this option can be used to provide extended AND logic. Thus if you search for:
Psion*organiser*serial
this will have the effect of a search for:
Psion AND organiser AND serial
with the proviso that the three words occur in the order given.
But note that this will not always be the best option. For example:
work*op
will find Workshop. But it will also find:
UNIX Workstation IXIWindows/XDesktop
By default the Extended wildcard option is on when you first run ArcScan, but your current setting of this option will be saved with the Start-up settings (see below).
To effect a printout, simply drag the icon in this box to a RISC OS printer driver compatible with your printer, and your finds will be rapidly printed.
Alternatively, you may optionally edit the name in the writable icon (ArcScanFinds by default), and then drag the text icon to a directory viewer of your choice. This will save the finds as a text file (i.e. of type ASCII, &FFF), and this may then be edited as required using Edit or similar.
| RUIv03i09 | |
| or | BBIv08i10 etc. |
The two-digit number following the "v" gives the volume number, and that following the "i", the issue number.
If issue files dragged to the ArcScan icon postdate the latest issue held in RAM, they will be loaded into RAM, automatically extending the database. In such cases you will find that the Save entry on ArcScan's icon bar menu is now selectable. Clicking on this will save back the latest volume of the magazine (which does not have to be complete) to disc. Note that it will only save the latest volume, so if you have dragged more than one file to the icon, and these files cover more than one volume, you will not be able to save back the lower of the two volumes. Thus if you are performing a multiple update (normally unnecessary), you should only drag the files of a single volume. Note that Volume files are held in the directory !ArcScan.RUdata and !ArcScan.BBdata, and have the names RUVol01, BBVol06 etc.
If you obtain your BEEBUG and RISC User issue update files from the RISC User magazine disc, they will automatically carry the correct filename and file type; and these files may be dragged directly from the magazine disc application into ArcScan, without first saving them to a directory viewer.
If you are updating by adding a new volume (rather than an issue file), just drag the new volume into the appropriate directory on the Desktop: ArcScan will automatically include it whenever it loads the corresponding database.
Note that ArcScan will work correctly with non-consecutive volume files, and with non-consecutive issue files.
Now open the hard disc directory in which you wish to install ArcScan, and copy the whole of ArcScan across by dragging the ArcScan icon from its directory viewer to the required destination. If your hard disc has no !System directory, then you should also drag this from the ArcScan disc to the root directory of your hard disc.
Because you are unlikely to require the references to pre RISC OS manuals, an alternative Custom file is provided. This also omits the indexes to Acorn's C and Fortran manuals, which many users are also unlikely to need. This has the name Custom1. To make use of this, open the !ArcScan directory by double-clicking on the ArcScan icon in its directory viewer while pressing the Shift key, then double-click on the Custom directory. Then simply drag the Custom1 file to the !ArcScan directory. Finally, you will need to delete (or rename) the original !Custom file, and rename the Custom1 file with the name !Custom (click the Menu button over the Custom1 file, and then follow the menu to Rename the file).
The !Custom file contains a single record for each selectable magazine or group of manuals. Each record contains 7 fields, and each field is terminated by a Carriage Return (ASCII 13). The start of each record is marked by a hash followed by a number (the number is ignored by the software, and is included for legibility). The end of the file is marked by a double hash (i.e. ##) followed by at least two Carriage Returns. Figure 1 indicates the structure of the file. This is reasonably self-explanatory, though fields 4, 5, 6 and 7 will need some clarification.
| Entry | Meaning |
#1 | Start new record |
RISC User | Menu entry |
R I S C U s e r | Screen title |
RUdata | Directory name |
RUvol | Generic Volume name |
0 | Data type |
5 | Line depth |
#2 | Next record start |
. | |
. | etc. |
. | |
## | End of file marker |
CR | |
CR |
Field 4 contains the name of the directory used to hold the data files for this entry. In most cases this will be the name of a directory within the !ArcScan application directory - for example:
RUdata
Alternatively, you may specify a full path at this point. For example:
adfs::ArcScanLib.$.MUdata
This tells ArcScan that data for Micro User is to be found in the root directory of the disc named "ArcScanLib". ArcScan will then prompt for this disc as and when required.
Field 5 contains the root name for magazine volume files. In this case, "RUvol". This means that ArcScan will look for volume files whose name is RUvolxx, where xx is a two-digit number. For both RISC User and BEEBUG this number is the magazine volume number. ArcScan can also cope with volume numbers which are expressed as three or four digit numbers - but you should not mix two, three or four digit volume numbers within a single directory.
Magazine files for Acorn User and Micro User use four digit volume numbers, where each represents the year of publication. There is one restriction when using volume numbers of three and four digits: you may not drag individual issue files to ArcScan for updating (since there is not room in the filename for the four digits). Updating must be performed by placing updated volume files into the appropriate directories.
In the case of non-magazine files, field 5 should consist of a single asterisk (followed as always by a Carriage Return). The effect of this is to place no restriction whatsoever on the filenames used for each non-magazine data file. The filename can then more fully reflect the purpose for which it is used. In the case of new manuals supplied with ArcScan, the names:
| 1RS_User | |
| 2RS_User2 | |
| 3RS_Basic | |
| and | 4RS_PRM |
have been used. The single digit at the start of each filename in this example is used to establish the alphabetical order in which ArcScan will load the files. This digit is not checked in any way, and may be absent from files created by the user.
Field 6 contains an indicator to the data type. It must be zero for magazine data or 1 for other data. Magazine data is distinguished by the fact that the data will come in a single file for each volume, and that this will contain a series of issue files. The way in which the issue and page numbers are treated is described under the heading Data Format below. The second data type is more generally applicable, and assumes that the data will be broken down into a number of works (anything from 1-20), that they may have entirely different titles, and are not subdivided into separate issues. Again the structure of this data is treated under Data Format below.
Field 7 indicates the so-called line depth. This is the number of lines that will be allocated to the display of each record, including one or more blank lines between records. For example, both the RISC User and BEEBUG displays use 5 lines: a title line, up to two lines of description, plus a reference line followed by one blank line. If you set it to 4 for RISC User, you will abolish the gap between the displayed records (except for those records which have only one line of description). There is no upper limit to line depth, and it could be as large as 30 or more. Ideally it should be set to leave a single line gap between the largest records. If records are encountered which are longer than the value set, you will lose the lower lines of display.
When creating custom files you must be wary of two sources of error:
^D
News: Faster Languages
RiscBASIC and RiscForth compilers
from Silicon Vision
\1 4
^D
Next record
.
.
.
\1 63
[
The reason for the slightly idiosyncratic structure is to maintain compatibility with BEEBUG MagScan files. Each record starts with "^" followed by zero or more ASCII characters (all of which are ignored), followed by ASCII 13. A number of single-line fields follow (each terminated by ASCII 13). The terminator is a backslash followed by two numbers (separated by a space). These are the issue and page number of the entry, and these are again terminated by ASCII 13. The volume number is obtained from the filename. The file is terminated by a left-hand square bracket, followed by ASCII 13.
Volume files consist of a sequence of issue files with the end of file markers stripped off. The volume file end is marked by a left hand square bracket. Normally ArcScan itself creates (and saves) volume files from a sequence of issue files. It does this when magazine issue files are dragged to its icon on the icon bar.
User Guide (RISC OS)
^
Abort on data transfer
Page(s) 473
\
^
*Access
Page(s) 24
\
.
.
.
\
[
Again the "^" and "\" are used to indicate the start and end of each record, and the "[" character the end of the file. The ASCII header at the start of the file must be no longer than 30 characters in length. This is displayed for identification purposes as the last line of each find so that more than one work may be used in any given database.
It will highlight a wide range of possible errors including:
Incorrect filetype
Too many fields in a record
Line too long
Missing start of record marker
Missing end of record marker
Invalid page number
Out of range page number
Unwanted control codes
Missing end of file marker
The utility is a relatively simple one, and will not run directly from the Desktop. To use it you must leave the Desktop (e.g. press F12), and load it into memory by making the directory $.!ArcScan.Utils the current directory - use
*Basic
*Dir $.!ArcScan.Utils
then
LOAD "ArcTest"
Then move to the directory which contains the file to be tested - e.g. use:
*Dir $.!ArcScan.RUData
to move to the RUData directory.
Now type RUN. The contents of the current directory will be displayed, and you will be asked for the name of the file that you want to check. When you have supplied this you will be asked if you want hard copy or not (Y or N), and whether the file is of magazine type or not (Y or N). The program will then check the supplied file.
If you opted for no hard copy, the display will pause at each data error, showing the line at fault, its line number (counting from the start of the file), and the type of error. If the hard copy option was chosen, all the results will be embodied in the printout.
It is then an easy matter to correct the data file using Twin or Edit. In either case you will need to select the Swap CR<>LF option in your editor to make the file legible (and don't forget to reset it before saving the amended file). Then use the Go To Line option in either editor to go directly to the errors. When you have re-saved the corrected file, pass it through the tester again to check that you have corrected all the mistakes.
There are four variables which may need to be customised before running the file tester. They appear in lines marked by REMs at the start of the program, and should be set as required. The first two, maglinedepth% and manlinedepth% should be set to one less than the value of line depth used in the !Custom file for magazine and manual type files respectively. Maxpage%is simply the highest page number that your magazine data may contain, and checkstring$ holds any word which must be present in the final line of non-magazine type data. It is currently set to "Page". If the word is not found at the end of any non-magazine record, an error is signalled. To make this test inactive, just set checkstring$ to "".